Skip to content

docs: document LS Login groups and facilities - #180

Merged
uniqueg merged 5 commits into
mainfrom
docs/176-ls-login-groups
Nov 18, 2026
Merged

uniqueg merged 5 commits into
mainfrom
docs/176-ls-login-groups

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds a section "Groups and facilities" to the LS Login operator page (docs/operators/ls-login.md), covering the six points of the issue:

  1. LS Login releases a group only if it is assigned to a resource on the facility of the client that requested the token; membership alone is not enough.
  2. Assign groups to the facility of the client users log in to (portal, front end); services that only validate its tokens need no groups of their own. Token exchange: entitlements are computed for the exchanging client; what reaches the end of a chain is still being tested (token-exchange testbed).
  3. Form of the entitlement value, with example VO and group names, and how to read the exact value from the user info.
  4. Groups appear in the user info only (eduperson_entitlement, needs the scope of that name), not in the access token; how FOCA-based services and TESK read them.
  5. A checklist for 403s: membership, release on the right client's facility, scope, exact value, caching.
  6. The test environment's 30-day rule (deactivation after another 14 days without action), and links to the Terms of Use for Service Providers and the LS AAI service level declaration.

Also: the second resource for the Lifescience VO members group, so that users outside the mapped groups can log in and get a 403 from the service, and who can assign groups (TrustedFacilityAdmin within the VO, otherwise the VO admins on request).

The LS Login row of the operator index (docs/operators/index.md) now names the new section.

Sources: Perun's public docs (Entitlements, Group entitlement, resource and role pages), the token-exchange testbed's "Group release" (assumptions A5, A9, A10, statements of the LS Login team), the LS Login discovery document, and the LS Login team's test-environment rule (WP2 minutes, December 2025). Generic: example VO and group names, no client IDs, no secrets, no personal data. last_verified stays null.

Light lane: docs only, one page, no code.

Verification

  • python scripts/check_names.py: passed.
  • DOCS_REGISTRY_OFFLINE=1 mkdocs build --strict: passed (links and anchors between pages checked).
  • pytest: 356 passed, 100% coverage.
  • After merging main and the Sourcery fixes (c0d35e0): CI green (CI passed, Docs, Test, PR title, CodeQL), Read the Docs build succeeded, Sourcery check passed.

Declined review findings

  • Sourcery "Match the 30-day rule": the page keeps the LS Login team's precise rule (at most 30 days in test, deactivation after another 14 days without action); the issue's wording was a shorter summary. Replied in the thread.

Open questions

None.

Closes #176

🤖 Generated with Claude Code

Summary by Sourcery

Document LS Login group release, facility configuration, entitlement handling, and authorization troubleshooting for service operators.

Enhancements:

  • Document how LS Login releases group entitlements based on client facilities and resources, including token-exchange considerations.
  • Add guidance for assigning groups, reading exact entitlement values, service consumption, and troubleshooting authorization failures.
  • Document test-environment service lifetime, applicable policies, and access behavior for users outside mapped groups.

Documentation:

  • Update the operator index and LS Login documentation with comprehensive guidance on groups, facilities, entitlements, and 403 troubleshooting.

Add a section "Groups and facilities" to the LS Login operator page:
how LS Login releases groups per client facility, which client needs
them, the second resource for users outside the groups, how to assign
groups, the form of the entitlement values and how to read them, how
the services read them, and a checklist for 403s. Also add the test
environment's 30-day rule and links to the terms and the service level
declaration.

Closes #176

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg uniqueg self-assigned this Nov 18, 2026
@sourcery-ai

sourcery-ai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Reviewer's Guide

Documentation

Document LS Login service registration, group release and facility assignment, entitlement handling, and troubleshooting so operators can configure access and diagnose 403 responses.

  • docs/operators/ls-login.md L9-12, L32-189

Update the operator index description to reflect the new LS Login guidance.

  • docs/operators/index.md L62

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

Update the LS Login row of the operator index for the new section
"Groups and facilities".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg uniqueg closed this Nov 18, 2026
@uniqueg uniqueg reopened this Nov 18, 2026
@read-the-docs-community

read-the-docs-community Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

@uniqueg
uniqueg marked this pull request as ready for review November 18, 2026 05:12
@sourcery-ai

sourcery-ai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Linked issues

Checked at commit f98a8e9

#176 docs: document LS Login groups and facilities · 8 of 8 met

# Requirement Status Notes
1 Explain that group release requires assignment to a resource on the facility of the client requesting the token; membership alone is not enough. ✅ Met The release rule and the distinction from group membership are explicit.
2 Explain which client's facility needs the groups, including that services which only validate that client's tokens do not need groups of their own. ✅ Met The page identifies the portal or front-end client, explains the role of token-validating services, and covers token exchange.
3 Show the entitlement value's form and how to read the exact value rather than guessing it. ✅ Met It gives the format and an example, and explains how to read the value from user info.
4 Say whether groups appear in the access token or user info, and how services read them. ✅ Met The page specifies the user-info claim and scope, and describes FOCA-based and TESK handling.
5 Give a 403 checklist covering membership, assignment to the client's facility, and exact mapped values. ✅ Met The checklist covers those points as well as scope and caching.
6 Link the service level declaration and terms, and note the test-environment deactivation timing. ✅ Met Both policies are linked; the page states a maximum 30-day test period followed by a further 14 days without action before deactivation.
7 Publish the section and link it from the operator index. ✅ Met The section is in the LS Login operator page, and the index entry describes it.
8 Enable an operator who did not write the page to set up group release for a new client. ✅ Met The page gives resource creation and group-assignment steps, explains the required Perun role and fallback to VO admins, and describes how to verify released values.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 4 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/operators/ls-login.md" line_range="175" />
<code_context>
+
+1. **Membership:** is the user a member of the group in Perun?
+2. **Release:** is the group assigned to a resource on the facility of the
+   client that the user logged in with (the token's `aud`), not of another
+   client?
+3. **Scope:** did the client request `eduperson_entitlement`, and does the
</code_context>
<issue_to_address>
**403 checks use wrong facility**

When a request uses an exchanged token and the exchanging client differs from the original login client, the checklist directs operators to use the interactive-login client’s facility, identified by the token’s `aud`, although the preceding guidance says entitlements are computed for the client calling the exchange. Operators check the wrong Perun facility and the 403 remains unresolved.

For exchanged tokens, direct operators to check the facility of the client calling the exchange rather than the interactive-login client identified by `aud`.
</issue_to_address>

### Comment 2
<location path="docs/operators/ls-login.md" line_range="34-36" />
<code_context>

+### Test and production
+
+LS Login keeps a new service in its test environment for at most 30 days.
+If its owner takes no action within another 14 days, LS Login deactivates
+the service (the LS Login team, December 2025). Move a service to
+production in time, as described in the [LS Login
+docs](https://lifescience-ri.eu/registering-integrating-and-managing-your-service/).
</code_context>
<issue_to_address>
**Match the 30-day rule**

The issue asks operators to be told that test-environment clients are deactivated after 30 days without action. This text instead describes a 30-day test period followed by another 14 days without action before deactivation.
</issue_to_address>

### Comment 3
<location path="docs/operators/ls-login.md" line_range="167" />
<code_context>
+  `security.access_control.group_mapping` (see [Cloud
+  Registry](cloud-registry.md#identity-provider)).
+- TESK reads one claim of the user info and accepts the listed values (see
+  [Onboard a Node](node-onboarding-tutorial.md#tesk)).
+
+### Checklist for a 403
</code_context>
<issue_to_address>
**TESK support looks confirmed**

When operators use TESK with LS Login and rely on the new description as confirmation that the integration works, when operators rely on this bullet to configure TESK with LS Login, it presents reading and accepting the groups as established behavior. The linked onboarding guide says LS Login token acceptance and TESK’s group model have not been verified, so operators are given more assurance than the documented integration supports.

Qualify the TESK bullet with the existing verification caveat, or document verified support before presenting it as established.
</issue_to_address>

### Comment 4
<location path="docs/operators/ls-login.md" line_range="150-151" />
<code_context>
+
+```bash
+read -rs TOKEN
+printf 'Authorization: Bearer %s\n' "$TOKEN" | curl -fsS -H @- \
+  https://login.aai.lifescience-ri.eu/oidc/userinfo
+```
+
</code_context>
<issue_to_address>
**User-info check hangs**

When the user-info endpoint accepts a connection but stops responding, or the network blackholes the request, `curl` has no connection or overall time limit, so a stalled LS Login endpoint or network leaves the operator's 403 diagnostic blocked instead of returning a bounded failure.

Add a suitable `--connect-timeout` and `--max-time` to the `curl` command.
</issue_to_address>

Sourcery assessment

Approval pending. 4 findings to address first.

Blocking findings: docs/operators/ls-login.md:175, docs/operators/ls-login.md:36, docs/operators/ls-login.md:167, docs/operators/ls-login.md:151


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread docs/operators/ls-login.md Resolved
Comment thread docs/operators/ls-login.md Resolved
Comment thread docs/operators/ls-login.md Resolved
Comment thread docs/operators/ls-login.md Resolved
uniqueg and others added 3 commits November 18, 2026 08:09
- Name the exchanging client's facility for exchanged tokens in the
  403 checklist.
- Say that TESK's acceptance of LS Login tokens is not verified yet.
- Bound the user info curl call with connect and total timeouts.

Addresses Sourcery review threads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg
uniqueg merged commit 94ce4f9 into main Nov 18, 2026
13 checks passed
@uniqueg
uniqueg deleted the docs/176-ls-login-groups branch November 18, 2026 07:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: document LS Login groups and facilities

1 participant